/* ========================================================================= */
/* ------------------------------------------------------------------------- */
/*!
  \file			ETSI_SText.h
  \date			september 2011
  \author		TNick

  \brief		Contains the definition for ETSI_SText class


  Copyright (c) 2011, Nicu Tofan
 All rights reserved.

 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions are met:
 * Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.
 * Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.
 * Neither the name of the copyright holder nor the
   names of its contributors may be used to endorse or promote products
   derived from this software without specific prior written permission.

 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS" AND
 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 DISCLAIMED. IN NO EVENT SHALL NICU TOFAN BE LIABLE FOR ANY
 DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

*/
/* ------------------------------------------------------------------------- */
/* ========================================================================= */
#ifndef __ETSI_STEXT_INC__
#define __ETSI_STEXT_INC__
//
//
//
//
/*  INCLUDES    ------------------------------------------------------------ */

#include	<sheet/ETSubItem.h>

/*  INCLUDES    ============================================================ */
//
//
//
//
/*  CLASS    --------------------------------------------------------------- */

/// simple sub-item capable to display a string
/**
*	This kind of ETSubItem is the building block for other complex items.
*	It does not host other sub-items.
*	@image html ETSI_SText.png
*
*	The reference point is placed at the half of the left edge. When the
*	height of the text changes, the bounding box will expand / contract
*	both upward and downward.
*
*	\section the_text	The strings
*	To retrieve the text contained by ETSI_SText, one may call text(). This
*	function returns an empty string if the sub-item is in default state,
*	while the user sees a special marker.
*
*	Changing the text is done with setText() function. If the provided string
*	is empty the state of the item is uninitialised and a default marker
*	will be presented to the user. If multiple sub-items belonging to the
*	same ETI_CplxTxt item have to be changed, \b b_recomp parameter may be
*	set to false to prevent the function from recomputing all sub-items
*	involved. The caller is responsible for calling ETI_CplxTxt::recompute()
*	when all changes were applied.
*
*	\section dimensions Dimensions. Bounding box.
*	The bounding box for this item is exactly the same as the bounding box for
*	the text. As previously mentioned, the reference point is placed on
*	the middle of the left side.
*
*/
class ETSI_SText : public ETSubItem DDHC_INHERIT		{ DDHC_CLASS

	//
	//
	//
	//
	/*  DEFINITIONS    ----------------------------------------------------- */

	/// default text to be displayed
#define	STEXT_DEFAULT		"?"

	/*  DEFINITIONS    ===================================================== */
	//
	//
	//
	//
	/*  DATA    ------------------------------------------------------------ */

private:


	/// the text to display
	QString		s_text;


	/*  DATA    ============================================================ */
	//
	//
	//
	//
	/*  FUNCTIONS    ------------------------------------------------------- */

public:

	/// constructor;
	ETSI_SText			( void );

	/// destructor;
	virtual				~ETSI_SText		( void );





	/* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! */
	/** @name The text    */
	//@{
	/* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! */


	/// retrieve the displayed text; if in default state the string is empty
	QString			text			( void )
	{ if (isInitialised()) return s_text; return QString(); }


	/// change the displayed text
	/**
	*	If the provided string is empty the state of the item
	*	is uninitialised and a default marker
	*	will be presented to the user. If multiple sub-items belonging to the
	*	same ETI_CplxTxt item have to be changed, \b b_recomp parameter may be
	*	set to false to prevent the function from recomputing all sub-items
	*	involved. The caller is responsible for calling ETI_CplxTxt::recompute()
	*	when all changes were applied.
	*/
	void			setText			(
		QString			new_text,
		bool			b_recomp = true
		);


	//@}
	/* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! */





	/* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! */
	/** @name Dimensions. Bounding box.    */
	//@{
	/* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! */


	/// get the bounding box of this item
	/**
 *	The function may or may not honor the flags representing the "dirty"
 *	state of that item regarding it's characteristics depending on
 *	\b b_full argument (when true the flags are ignored)
 */
	void				recompute		(bool b_full);


	//@}
	/* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! */




protected:


	/* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! */
	/** @name Others    */
	//@{
	/* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! */


	/// paint the element on provided surface
	void		paint			(
		ETSheetView *	vp,
		QPainter *		painter,
		QPointF			pt_ref
		);

	//@}
	/* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! */




	/* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! */
	/** @name Navigation    */
	//@{
	/* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! */


//	/// recieves navigation keys
//	void		navKey				(
//		ETSheetView *		vp,
//		Qt::Key 			key
//		);


	//@}
	/* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! */




	/* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! */
	/** @name Others    */
	//@{
	/* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! */

protected:

	/// called to determine the sub-item that was hit
	void		hitTest		(HtData * h_data);


public:

	/// identifies the type of the sub-item
	SIType		type		( void ) const { return TYSTEXT;}


	//@}
	/* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! */






	/* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! */
	/** @name Save and load	*/
	//@{
	/* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! */

public:


	/// creates a new item based on DOM element's content
	/**
	*	It is the responsability of the caller to properly insert resulted
	*	sub-item in a chain.
	*
	*	@return either the item that was initialised or NULL for errors
	*/
	static ETSI_SText *		loadXML			(
		QDomElement		dom_e	/**< data source */
		);


	/// saves the properties of this item to provided DOM element
	/**
	*	Internally, the inherited class needs to call saveXMLCmn()
	*	to save common properties hosted by the ETSubItem class
	*/
	void					saveXML			(
		QDomElement		dom_e
		);

	//@}
	/* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! */


	/*  FUNCTIONS    ======================================================= */
	//
	//
	//
	//

};	/*	class ETSI_SText	*/

/*  CLASS    =============================================================== */
//
//
//
//
#endif // __ETSI_STEXT_INC__
/* ------------------------------------------------------------------------- */
/* ========================================================================= */
